LibComponentLogging

Logging for Objective-C with log levels and log components.

LibComponentLogging is a small logging library for Objective-C on Mac OS X and iOS which provides log levels, log components, and pluggable logging back-ends, e.g. writing log messages to a file, or sending them to the system log.

Found a bug? Missing a feature? Drop a line to logging@0xc0.de, or create an issue in one of the repositories on GitHub, or fork and contribute.

Download Overview Getting started Read more

core

Core 1.3.3, 2013-11-01

back-end

extension

A short overview of LibComponentLogging:

Log levels

LibComponentLogging provides built-in log levels for distinguishing between error messages, informational messages, and fine-grained trace messages for debugging.

Log components

Log components can be used to identify different parts of your application or framework. A log component contains a unique identifier, a short name which is used as a header in a log message, and a full name which can be used in a user interface.

Level × component

Each log component has its own active log level. This way it's possible to enable/disable logging only for certain parts of your application or framework.

Low overhead

Logging is based on a log macro which checks the active log level before constructing the log message and before evaluating log message arguments. Your log statements can stay in your code, they consume only little runtime overhead if logging is disabled.

Code completion

Symbols for log components and log levels work with Xcode's code completion:

Meta data

Public data structures expose information about log components, e.g. headers and names, and log levels.

Logging back-ends

The core part of LibComponentLogging focuses on log levels and log components. It provides a simple delegation mechanism for plugging in a specific logging back-end based on your application/framework's requirements, e.g. a back-end which writes to the system log, or a back-end which writes to a log file, or a back-end which integrates a remote logger. The logging back-ends define the actual log output format and add additional details, e.g. time stamp, file name, line number, class and method.

Extensions

LibComponentLogging's core files contain a simple include mechanism for extension modules. Extensions may provide additional log macros or mechanisms to store/restore log level settings from user defaults, files, environment variables, etc.

Assembled at build-time

LibComponentLogging uses a set of configuration header files to configure log components and to register the logging back-end and extensions at build-time. You only need to include lcl.h in your prefix header file; the configuration files for log components, the logging back-end and extensions are included internally.

Optionally ARCed

LibComponentLogging can be used with Automatic Referencing Counting (ARC), or with traditional code that uses retain/release/autorelease calls.

1. Download

Download the core files and one logging back-end from the project pages on GitHub:

core

Library core

back-end

Optionally download extensions:

extension

2. Install

Extract the files and copy the extracted files to your application/framework's source directory.

Open Xcode and add all files of the library to your project. Xcode will automatically add the library's implementation files to your project's target.

3. Configure

Create your application/framework's lcl_config_components.h file.

Create a lcl_config_logger.h file and set up the logging back-end, e.g. set the maximum file size and the name of the log file for the LogFile back-end.

Create lcl_config_extensions.h for extensions and optionally add #import statements for extensions you'd like to use.

Add an #import "lcl.h" statement to your source files, e.g. to your project's prefix header file.

4. Use

Define your log components in lcl_config_components.h.

Add lcl_log(...) or lcl_log_if(...) log statements to your code.

Configure the active log levels for your log components, e.g.

lcl_configure_by_identifier("*", lcl_vWarning);

Note: Since version 1.3 of the library core, an NSLog-based default logging back-end will be used if no back-end is configured via lcl_config_logger.h.

Quick start

For a quick start with the LogFile logging back-end, simply clone the LogFile example project from GitHub:

git clone git://github.com/aharren/LibComponentLogging-LogFile-Example.git

The project contains an Xcode project, the core files of LibComponentLogging, the LogFile logging back-end, the qlog extension, some preconfigured log components, and some example log statements in the main.m file.

CocoaPods

See the CocoaPods section below for information about using LibComponentLogging with the CocoaPods dependency manager.

core

Examples
Core structure
Logging interface
Log levels
Log components
Runtime configuration

back-end

LogFile
SystemLog
NSLog
NSLogger
Crashlytics

extension

qlog
UserDefaults

integration

embedded
CocoaPods and configure

Some examples of using LibComponentLogging's core logging interface, compared to NSLog-based logging:

Log statements

Simple NSLog-based logging:

NSLog(@"message, %@", arg1);

LibComponentLogging-based logging with log components and log levels:

lcl_log(lcl_cMain, lcl_vInfo, @"message, %@", arg1);

Or, when using the qlog extension:

#define ql_component lcl_cMain

qlinfo(@"message, %@", arg1);

The lcl_log log macro checks the log component's active log level before constructing the log message and before evaluating log message arguments. So, if Main's log level is not at least set to Info, no log message will be written.

Conditional logging

Conditional logging with NSLog:

if (condition) {
  NSLog(@"message, %@", arg1);
}

Conditional logging with LibComponentLogging:

lcl_log_if(lcl_cMain, lcl_vInfo, condition, @"message, %@", arg1);

Or with the qlog extension:

qlinfo_if(condition, @"message, %@", arg1);

The condition is only evaluated if component Main is at least configured with log level Info.

Turn logging off, and on

Remove NSLog statements manually:

// NSLog(@"message, %@", arg1);

Or, use an #ifdef to include them only in debug builds:

#ifdef DEBUG
NSLog(@"message, %@", arg1);
#endif

Or, create your own logging macro and hide all the details in the macro definition:

#ifdef DEBUG
#define MyLog(format, ...)         \
  do {                             \
    NSLog(format, ##__VA_ARGS__);  \
  } while (0)
#else
#define MyLog(format, ...)         \
  do {                             \
  } while (0)
#endif

MyLog(@"message, %@", arg1);

Or, introduce a logging flag for checking at runtime:

if (logging_enabled) {
  NSLog(@"message, %@", arg1);
}

Or, ...

With LibComponentLogging, simply keep your log statements in your code.

And, disable logging for all components at runtime:

lcl_configure_by_identifier("*", lcl_vOff);

Or, enable logging for all components at level Warning and higher, and component Main at level Trace and above:

lcl_configure_by_identifier("*", lcl_vWarning)
lcl_configure_by_component(lcl_cMain, lcl_vTrace);

Or, use the UserDefaults extension to restore log level settings from the standard user defaults:

[LCLUserDefaults restoreLogLevelSettingsFromStandardUserDefaults];

Or, remove all log statements at build-time, if you really need it:

Define _LCL_NO_LOGGING in your build settings or in your prefix header file before importing lcl.h.

Download latest releases

Overview

Log levels

Log components

Level × component

Low overhead

Code completion

Meta data

Logging back-ends

Extensions

Assembled at build-time

Optionally ARCed

Getting started

1. Download

2. Install

3. Configure

4. Use

Quick start

CocoaPods

Read more

Examples core

Log statements

Conditional logging

Turn logging off, and on

Core structure core

Logging interface core

Log levels core

Log components core

Runtime configuration core

LogFile back-end

SystemLog back-end

NSLog back-end

NSLogger back-end

Crashlytics back-end

qlog extension

UserDefaults extension

embedded integration

CocoaPods and configure integration

GitHub repositories